package de.graph.common;

import java.util.Collection;


/**
 * A graph is a container object for a collection of vertices and a collection edges.
 */
public interface Graph {

    /**
     * Create a new vertex and add it to the graph.
     * 
     * @return the newly created vertex
     */
    public Vertex createVertex();

    /**
     * Create a new vertex with a given label and add it to the graph.
     * 
     * @param label the label associated with the vertex
     * @return the newly created vertex with a label 
     * @see Element#getLabel()
     */
    public Vertex createVertex(String label);
    
    /**
     * Remove the provided vertex from the graph.
     * Upon removing the vertex, all the edges by which the vertex is connected will also be removed.
     *
     * @param vertex the vertex to remove from the graph
     */
    public void removeVertex(Vertex vertex);

    /**
     * Returns a collection of all the vertices in the graph. 
     *
     * @return a collection of all the vertices
     */
    public Collection<Vertex> getVertices();

    /**
     * Returns a collection of all the vertices in the graph for a specified label. 
     *
     * @param label the label associated with the vertex
     * @return a collection of all the vertices for a label
     * @deprecated not implemented yet (indexing necessary)
     */
    public Collection<Vertex> getVertices(String label);
    
    /**
     * Adds an edge between two vertices to the graph.
     *
     * @param source the source vertex of the edge
     * @param target the target vertex of the edge
     * @return the newly created edge
     * 
     * @throws IllegalArgumentException if source or target are <code>null</code>
     */
    public Edge createEdge(Vertex source, Vertex target);

    /**
     * Adds an edge between two vertices to the graph for a specified label.
     *
     * @param source the source vertex of the edge
     * @param target the target vertex of the edge
     * @param label  the label associated with the edge
     * @return the newly created edge with a label
     * 
     * @throws IllegalArgumentException if source or target are <code>null</code>
     */
    public Edge createEdge(Vertex source, Vertex target, String label);
    
    /**
     * Remove the provided edge from the graph.
     *
     * @param edge the edge to remove from the graph
     */
    public void removeEdge(Edge edge);

    /**
     * Returns a collection of all the edges in the graph. 
     *
     * @return a collection of all the edges
     */
    public Collection<Edge> getEdges();

    /**
     * Returns a collection of all the edges in the graph for a specified label. 
     *
     * @param label the label associated with the edges
     * @return a collection of all the edges for a label
     * @deprecated not implemented yet (indexing necessary)
     */
    public Collection<Edge> getEdges(String label);

    /**
     * Remove all the edges and vertices from the graph.
     */
    public void clear();

	/**
	 * Return <code>true</code> if graph is directed, <code>false</code>
	 * otherwise.
	 * 
	 * @return boolean - <code>true</code> if graph is directed
	 * @deprecated the type will be used later
	 */
	public boolean isDirected();
}
